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(54) Integrated software command specification and documentation system 

(57) An integrated software command specification 
and documentation system is disclosed. The user docu- 
mentation for a given input command or output report 
may be automatically generated by placing documenta- 
tion information directly in the software specification that 
defines the command or report. A list of documentation 
keywords and associated rules are utilized to identify and 
process the documentation information. A compiler will 
utilize the documentation keywords to recognize the doc- 
umentation information in the command specification 
and place the documentation information In an appropri- 
ate segment of a documentation file associated with the 
command or report. Documentation information that may 
be needed for a plurality of command specifications, 
such as parameter definitions for parameters associated 
with a plurality of commands, may be stored in a docu- 
mentation library. 
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Description 

FIELD OF THE INVENTION 

The present Invention relates to a system for docu- s 
menting software, and more particularly, to a method and 
apparatus for automatically generating user documenta- 
tion for software commands and output reports from doc- 
umentation information that has been placed directly in 
a software specification. 

BACKGROUND OF THE INVENTION 

While software may be the medium for communicat- 
ing with a computing system, it is the accompanying doc- 
umentation that will explain the operation of that software 
to those who wish to use it. Accordingly, the importance 
of clear and accurate documentation cannot be overem- 
phasized. In order to effectively utilize a particular soft- 
ware program or command, the documentation accom- 
panying that software should clearly set forth the pur- 
pose of the software and provide a detailed description 
of the input data and any output results, such as reports 
and displays, that are produced by the software. 

Because of the frequency with which many software 
programs are updated, programmers typically find it to 
be quite burdensome to keep the accompanying docu- 
mentation up to date. Nonetheless, it is critical that the 
documentation is properly revised with each software 
update so that the documentation may accurately reflect 
the operation of the software at all times. 

Unfortunately, with conventional programming tech- 
niques, a programmer will typically develop or modify a 
software program in a programming environment, and 
then the programmer or a third party must utilize a sep- 
arate environment, such as a text editor, to develop or 
modify the accompanying documentation. Accordingly, 
changes that are made in the software do not promptly, 
accurately and invariably appear in the accompanying 
documentation. 

One existing software documentation system, de- 
scribed in U.S. Patent No. 4,860.203 and hereinafter re- 
ferred to as the "Corrigan" system, allows design docu- 
mentation information for a software program to be 
placed directly in a high level language source code pro- 
gram for extraction by a compiler. The extracted docu- 
mentation information is sequentially placed by the com- 
piler in a separate design documentation file, in addition, 
the Corrigan software documentation system includes a 
mechanism to ensure that every implementation code 
statement of the software program has at least one as- 
sociated design comment describing the code operation. 

While the Corrigan software documentation system 
provides an effective mechanism for extracting docu- 
mentation information from a source code file, the ex- 
tracted documentation information may not be reorgan- 
ized by the compiler in any manner. The Corrigan soft- 
ware documentation system utilizes a single documen- 



tation indicator, i.e., an exclamation mark, to identify doc- 
umentation statements in the source code program. Ac- 
cordingly, the extracted documentation information can- 
not be classified or reorganized in any manner and must 
be placed in a single design documentation file in the 
order in which it was extracted from the source code pro- 
gram. 

As is apparent from the above deficiencies with con- 
ventional documentation systems, a need exists for an 
improved documentation management system that is in- 
tegrated in a single environment with the programming 
tools and allows extracted documentation information to 
be processed or reorganized. An integrated program- 
ming and documentation system will make it easier for 
programmers to write consistent and complete docu- 
mentation, and will thereby facilitate the maintenance of 
accurate documentation. 

SUMMARY OF THE INVENTION 

Generally, according to one aspect of the invention, 
the documentation for a particular input command or out- 
put report may be automatically generated by placing 
documentation information directly in the software spec- 
ification that defines the command or report. 

The invention includes a method for generating user 
documentation for a software command to be executed 
by a computing system. The computing system will in- 
terpret the software command based on a high level lan- 
guage command specification that includes command 
specification information identified by one or more com- 
mand keywords. The high level language command 
specification Is translated Into a form that may be exe- 
cuted by the computing system and the user documen- 
tation includes a plurality of segments. The documenta- 
tion method comprises the steps of: defining a plurality 
of documentation keywords for identifying documenta- 
tion information statements in the command specifica- 
tion that describe the operation of the software com- 
mand, each of the documentation keywords being asso- 
ciated with one of the segments of the user documenta- 
tion; incorporating into the high level language command 
specification one or more of the documentation infomna- 
tion statements, wherein each of the documentation in- 
formation statements are identified in the command 
specification by one of the predefined documentation 
keywords; parsing the high level language command 
specification; extracting from the parsed command spec- 
ification each of the documentation Information state- 
ments identified by one of the predefined documentation 
keywords; and placing each of the extracted documen- 
tation information statements in the segment of the user 
documentation corresponding to the associated docu- 
mentation keyword. 

In addition, the invention includes an apparatus for 
generating user documentation for a software command 
to be executed by a computing system. The computing 
system interprets the software command based on a 
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high level language command specification that includes 
command specification information identified by one or 
more command keywords. The high level language com- 
mand specification is translated into a form that may be 
executed by the computing system. The documentation 
apparatus comprises: a documentation keyword data 
base for storing a plurality of documentation keywords 
for identifying documentation information statements in 
the command specification that describe the operation 
of the software command, each of the documentation 
keywords having an associated rule to be performed 
upon recognition of the associated documentation key- 
word in the command specification; means for incorpo- 
rating into the high level language command specifica- 
tion one or more of the documentation information state- 
ments, wherein each of the documentation information 
statements are identified in the command specification 
by one of the predefined documentation keywords; a 
parser for parsing the high level language command 
specification and processor means for extracting from 
the parsed cof iwivtud specification each of the documen- 
tation inlorrrviton statements identified by one of the pre- 
defined documentation keywords and for processing 
each of the extracted documentation information state- 
ments based on the rule associated with the documen- 
tation keyword Identifying the documentation information 
statement. 

A more complete understanding of the present in- 
vention, as well as further features and advantages of 
the invention, will be obtarned by reference to the de- 
tailed description and drawings. 

BRIEF DESCRIPTION OF THE DRAWINGS 

FIG. 1 is a schematic block diagram illustrating an 
integrated software command specification and 
documentation system according to the present 
invention; 

FIGS. 2a through 2d, collectively, illustrate a sample 
command specification source code file that pro- 
vides specification and documentation information 
for an input command and associated output report; 

FIGS. 3a through 3e, collectively, are a flow chart 
describing an exemplary documentation process as 
utilized by a documentation file generator in analyz- 
ing a parse tree and generating user documentation; 

FIG. 4 is an illustrative command documentation file 
for the command specified in FIGS. 2a through 2d; 
and 

FIG. 5 is an illustrative report documentation file for 
a report generated by the command specified in 
FIGS. 2a through 2d. 



DETAILED DESCRIPTION 

An integrated software command specification and 
documentation system according to the present inven- 
5 tion is illustrated in FIG. 1 . The integrated software com- 
mand specification and documentation system disclosed 
herein is a software generation system (SGS) based 
software development tool. The software generation 
system may be embodied as a compiler or a similar sys- 
tem capable of translating command specifications into 
a machine readable format. 

As is well-known, a process or a series of computer 
instructions to be performed by a computing system 85 
may be initiated by a user at run-time by entering a soft- 
ware command 80 that is associated with the desired 
process or series of instructions. As discussed further 
below, the computing system 85 knows how to interpret 
the entered software command 80 based on a command 
specification 10 that has been previously processed by 
a compiler 15 at compile time. The software command 
80 may be entered by a user into the computing system 
85 by, for example, entering an alphanumeric label from 
a keyboard, depressing a function key on a keyboard, or 
selecting an icon using a graphical user interface. 

An illustrative command specification, such as the 
command specification 10, is discussed below, in con- 
junction with FIGS. 2a through 2d. Typically, the com- 
mand specification 10 is written in a high level language 
that is then translated into a computer readable form by 
a compiler, such as the compiler 1 5, as shown in FIG. 1 . 
As discussed further below, the compiler 1 5 will analyze 
the command specification 10 at compile time and es- 
tablish an entry 90 in a command data base 35 for each 
specified command. 

As discussed further below, the entry 90 in the com- 
mand data base 35 for each software command 80 will 
typically identify the associated command and set forth 
the series of computer instructions that should be per- 
formed by the computing system 85 upon entry of the 
command 80 into the computing system 85 at run-time. 
Alternatively, the entry 90 can identify the process or se- 
ries of computer instructions that should be performed 
by the computing system 85 by storing an indication of 
where the desired process or series of computer instruc- 
tions is stored, such as a software file or other memory 
location. In addition, the entry 90 will typically include in- 
formation about any parameters that may be required to 
execute the command 80. In this manner, when a soft- 
ware command 80 is entered by a user into the comput- 
ing system 85 at run-time, the appropriate entry 90 in the 
command data base 35 may be accessed by the com- 
puting system 85 in order to properly execute the appro- 
priate process or series of computer instructions. 

The computing system 85 may be embodied as any 
programmed digital data processor capable of receiving 
command inputs from a user and executing an associ- 
ated process or series of computer instructions, such as 
a general purpose computer executing applications soft- 
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ware or a dedicated program controlled processor, such 
as a telecommunicalions switch. 

As shown in FIG. 1 , the integrated software specifi- 
cation and documentation system preferably employs a 
compiler 15. as modified herein to provide documenta- 
tion generation facilities. A command specification 10 is 
received by the compiler 1 5 from an input medium, such 
as a computing system having programming tools or, al- 
ternatively from a storage medium. 

The command specification 10 is analyzed at com- 
pile time by a parser 20 which converts the command 
specification 1 0 into a parse, which may take any one of 
a number of well-known forms, such as a parse tree 22. 
The operations of the parser 20, and the hierarchical re- 
lationship of the resultant parse tree 22, are well known 
to those skilled in the art. Generally, a compiler, such as 
the compiler 15, parses the command specification and 
analyzes the parse tree 22 by referencing a stored list of 
keywords and associated rules that must be performed 
upon recognition of a keyword in the parse tree 22. 

A file code generator 25 preferably consists of a 
processor 32 and a memory unit 34. As is well-known, a 
command specification process 28, stored in the mem- 
ory unit 34, is executed by the processor 32 to analyze 
the parse tree 22 by searching for predefined command 
keywords in the parse tree 22. The list of predefined com- 
mand keywords are stored in a command keyword data 
base 30. which may be an independent database in the 
memory unit 34, as shown in FIG. 1 , or embedded in the 
code for the command specification process 28. For 
each predefined command keyword, the command key- 
word data base 30 stores an associated rule that must 
be performed by the command specification process 28 
upon recognition of the command keyword and associ- 
ated data in the parse tree 22. 

Typically, the command specif ication process 28 will 
search the parse tree 22 for command keywords asso- 
ciated with the specification information that is necessary 
to populate the entry 90 in the command data base 35 
for the respective command 80. As previously indicated, 
each entry 90 in the command data base 35 preferably 
includes a cell 92 that identifies the associated command 
and a cell 94 that sets forth the series of computer in- 
structions that should be performed by the computing 
system 85 upon entry of the command into the comput- 
ing system at run-lime. Alternatively, the cell 94 can iden- 
tity the process or series of computer instructions that 
should be performed by the computing system 85 by 
storing an indication of where the desired process or se- 
ries of computer instructions is stored. In addition, the 
entry 90 will preferably Include a cell 96 that will typically 
include information about any parameters that may be 
required to execute the command 80, such as the pa- 
rameter type, and the valid range of the parameter val- 
ues. 

In order for a software command to be effectively 
utilized by a user, the command must be properly docu- 
mented. Typically, the user documentation associated 
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with a command, hereinafter referred to as command 
documentation, includes a description of the purpose of 
the command, as well as a description of how to use the 
command. The description of how to use the command 
5 preferably includes a description o1 the parameters as- 
sociated with the command. 

According to one feature of the Invention, the com- 
mand documentation for a given command can be auto- 
matically generated by placing the necessary documen- 
10 tation information directly in the associated command 
specification together with one or more predefined doc- 
umentation keywords, as described below. 

A documentation file generator 40 preferably con- 
sists of a processor 42 and a memory unit 44. The mem- 
15 ory unit 44 stores a documentation process 48, dis- 
cussed below in conjunction with FIGS. 3a through 3e, 
that is executed by the processor 42 to identify and an- 
alyze the documentation information that appears in the 
parse tree 22. Preferably, the list of predefined documen- 
tation keywords and associated rules are stored in a doc- 
umentation keyword data base 45, which may be an In- 
dependent data base In the memory unit 44, as shown 
in FIG. 1, or embedded in the code for the documentation 
process 48. 

As discussed further below, the documentation 
process 48 will search. the parse tree 22 in order to iden- 
tify documentation keywords and to extract the associ- 
ated documentation information. If the documentation 
process 48 identifies a documentation keyword in the 
parse tree 22, the appropriate rule associated with the 
documentation keyword will be performed by the docu- 
mentation process 48 on the data that has been placed 
with the associated documentation keyword in the re- 
spective node of the parse tree 22. In addition, as dis- 
cussed further below, the documentation process 48 
may Implement rules requiring a certain portion of the 
source code to include documentation information there- 
by ensuring the consistency and completeness of the 
documentation. In a preferred embodiment, the docu- 
mentation file generator 40 will place the documentation 
Information that has been identified In the parse tree 22 
in a command documentation file 400 or a report docu- 
mentation file 500, as discussed further below in con- 
junction with FIGS. 4 and 5. 

In a preferred embodiment, a documentation library 
75, which may be embodied as a software file stored in 
the memory unit 44, is provided to store parameter def- 
initions or other information that may be needed by a plu- 
rality of command specifications. Thereafter, the com- 
mand specification for each command that utilizes the 
parameter or other information will reference the more 
detailed information that is stored in the documentation 
library 75. In this manner, the effort needed to subse- 
quently define or modify the parameter for each com- 
mand is reduced and the consistency of the parameter 
definition for each command is ensured. 

It is to be understood that although the file code gen- 
erator 25 and the documentation file generator 40 of the 
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compiler 15 have been illustrated as employing two in- 
dependent processors 32, 42 and two independent 
memory units 34, 44, a single integrated processor or 
associated memory unit could be employed to imple- 
ment the command specification process 28 and the s 
documentation process 48. as would be apparent to one 
skilled in the art. In addition, since there may be some 
overlap of the command keywords and the documenta- 
tion keywords, as discussed further below, the command 
keywords and documentation keywords, as well as the io 
associated rules, may be stored in a single data base, 
that may be accessed by both the command specifica- 
tion process 28 and the documentation process 48. Fur- 
thermore, it is noted that the documentation library 75 
may be part of a broader library specification that may is 
also Include additional command specification informa- 
tion. 

A documentation processor 50 is preferably provid- 
ed to process the command and report documentation 
files 400, 500, respectively, generated by the documen- 
tation file generator 40 in order to generate formatted 
pages for a user documentation manual. Preferably, the 
documentation processor 50 will generate user docu- 
mentation manuals that conform to a style guide or an- 
other body of rules that govern the layout and content of 25 
the documentation information. The documentation 
processor 50 preferably presents the user documenta- 
tion to a user by means of a display 60 or a hard copy 
generated by a printer 65. 

In the embodiment discussed herein in conjunction 30 
with FIGS. 2 through 5. the documentation keyword data 
base 45 Includes the following Illustrative documentation 
keywords, discussed further below: PURPOSE, PA- 
RAMETER DESCRIPTION, WARNING, PAGE and RE- 
SPONSES. As discussed below In conjunction with the 3S 
documentation process 48, shown in FIGS. 3a through 
3e, one or more documentation rules can optionally be 
defined for each documentation keyword. The documen- 
tation rules can allow the associated documentation 
statements to be reorganized for placement In the user 40 
documentation, as well as maintain the consistency and 
completeness of the user documentation. The list of doc- 
umentation keywords may be supplemented by adding 
additional keywords and associated documentation 
rules to the documentation keyword data base 45, as 45 
would be apparent to one skilled In the art. 

An illustrative command specification 1 0 for a com- 
mand, op-wspos, is shown In FIGS. 2a through 2d. The 
SPECIFICATION keyword in line 02 of FIG. 2a is an in- 
dication to the compiler 1 5 that the software being proc- 50 
essed Is a specification for a given input command or 
output report. The PAGE keywords In lines 04 and 16 of 
FIG. 2a provide a mechanism for allowing a programmer 
to specify a particular page or section of a documentation 
manual where the documentation for a particular com- 55 
mand or report should appear. For example, a program- 
mer may desire to group the documentation for a number 
of related commands or reports on a single page. 
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Thus, lines 04 through 14 specify the PAGE require- 
ments for the op-wspos command, and lines 1 6 through 
26 specify the PAGE requirements for the associated 
op-ivspos report. The part and subject fields of the PAGE 
specification, as shown in lines 06 and 18 and lines 08 
and 20 of the specification of FIG. 2a, respectively, allow 
the programmer to specify the chapter and section, re- 
spectively, where the documentation information for the 
current command or report should appear. 

In addition, If the command or report Indicated in 
lines 12 and 24, respectively, are particularly relevant to 
one or more features of a computing system, the pro- 
grammer may specify this information in the features 
field, as shown in lines 10 and 22 of the specification of 
FIG. 2a. The pathname field in lines 14 and 26 Indicate 
where the command and report documentation files for 
the associated command and report, respectively, are 
stored. It is noted that if a programmer would like docu- 
mentation for a plurality of commands or reports to ap- 
pear on the same documentation page, the information 
indicated in line 12 and line 24, respectively, can include 
a list of the desired commands or reports to appear on 
the same page. 

The COMMAND keyword in line 30 is an indication 
to the compiler 15 that lines 30 through 160 of the spec- 
ification will define a command. The INITIATION MES- 
SAGE keyword in line 30, together with the entry in line 
40, provide a mechanism for associating the command 
label with the process or series of computer instructions 
that should be performed by the computing system 85. 
When the associated software command 80 is entered 
into the computing system 85 at run-time, the computing 
system 85 will retrieve the indication from the command 
data base 35 of how the desired process or series of 
computer Instructions is Initiated and thereafter send the 
appropriate message to execute the associated se- 
quence of instructions. Alternatively, line 40 could list the 
series of computer instructions that should be performed 
by the computing system 85 at run-time. 

The TEMPLATE keyword In line 50 provides a tem- 
plate for the usage of the command and associated pa- 
rameters, and indicates to the compiler that the input 
command and parameters must follow the syntax set 
forth in line 60, in a known manner. The command name 
and parameter Information that appears In line 60 will 
typically be placed by the compiler 15 in the command 
data base 35, as previously indicated. In addition, the 
TEMPLATE information will be placed in the command 
documentation file 400, as described below. 

The PURPOSE keyword in line 70 Is a documenta- 
tion keyword that will provide an indication to the com- 
piler 1 5 that the character string that follows In line 80 is 
a description of the purpose of the command and should 
appear in the command documentation, as described 
below. 

Lines 90 through 140 of the command specification 
define the type and range requirements of the numeric 
command parameter, tp, in a known manner. The PA- 
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RAMETER DESCRIPTION keyword in line 1 50 is a doc- 
umentation keyword that indicates to the compiler 1 5 that 
the character string that follows In line 160 is a descrip- 
tion of the associated command parameter and should 
appear in the command documentation, as described 
below. The defined parameter information would typical- 
ly be placed by the compiler 15 in the command data 
base 35, as previously indicated. 

Very often, when a software command 80, such as 
the op-wspos command specified in FIGS. 2a through 
2d, is entered into a computing system 85 at run-time, 
the computing system 85 will take an action based on 
the input command 80 and then produce an output, such 
as a printed or displayed report. In order for the report to 
be effectively utilized and understood by a user, the re- 
port must be properly documented. Typically, the user 
documentation associated with a report, hereinafter re- 
ferred to as the report documentation, includes a de- 
scription of the meaning and format of the report. 

As is well-known, when the execution of a command 
80 produces an associated report, the command speci- 
fication 10 will typically include a specification of the as- 
sociated report, as discussed further below. As shown In 
FIGS. 2a through 2d, the command specification 10 as- 
sociated with the op-wspos command will include a re- 
port specificatbn portion in lines 200 through 890, as in- 
dicated by the REPORT keyword in line 200 (FIG. 2b). 

The INITIATION MESSAGE keyword in line 210 of 
the command specification provides a mechanism for 
associating the report with the message In line 220 that 
will initiate the generation of the desired report, in a 
known manner The message in line 220 will typically be 
placed by the compiler 15 in the command data base 35. 

The TEMPLATE keyword in line 230 indicates to the 
compiler 15 that lines 240 through 270 of the command 
specification provide a template for the report format. 
Lines 240 through 260 provide the report headings, and 
line 270 indicates the parameter values that should be 
utilized to populate the report, in a known manner. 

The PURPOSE keyword in line 280 of the specifica- 
tion is a documentation keyword that will provide an in- 
dication to the compiler 1 5 that the character string that 
follows in line 290 is a description of the report, that 
should appear in the report documentation, as described 
below. 

Lines 300 through 890 of the specification shown in 
FIGS. 2b through 2d define the type and range require- 
ments of each of the parameters that appear in the 
op-wspos report, in a known manner The PARAMETER 
DESCRIPTION keywords in lines 360, 440, 520, 600, 
680 and 880 Indicate to the compiler 1 5 that the charac- 
ter strings that follow are descriptions of the report pa- 
rameters, as described above. Similarly, the parameter 
mode accepts one of four character string Inputs, as set 
forth In the enumerated list in lines 720 through 840, in 
a known manner. The DESC keywords below each 
ENUM keyword, such as in lines 750, 780, 81 0 and 840, 
provide an indication to the compiler 15 that the charac- 
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ter string that follows is a description of the associated 
mode value - 

The documentation process 48 embodying the prin- 
ciples of the present invention, illustrated in FIGS. 3a 
5 through 3e. will be entered at step 300 to analyze the 
command specification parse tree 22. It is to be under- 
stood that although the documentation process 48 is dis- 
cussed below using a set of illustrative command and 
documentation keywords, other keywords could be utl- 
10 lized without departing from the scope or spirit of the in- 
vention, as will be apparent to one skilled In the art from 
the present discussion of the invention. 

A test is performed during step 302 to determine if 
the command specification parse tree 22 includes a 
15 PAGE keyword. The PAGE keyword will preferably allow 
a programmer to define a particular page or section of a 
documentation manual where the documentation for a 
particular command or report should appear. For exam- 
ple, a programmer may desire to group the documenta- 
20 tion for a number of related commands and reports on a 
single page. If it is determined during step 302 that the 
command specification parse tree 22 does include a 
PAGE keyword, the documentation process 48 will proc- 
ess the PAGE information and identify during step 303 
25 the list of commands or reports that should appear on 
the same documentation page, as well as the appropri- 
ate page or section where the current documentation 
should be placed. 

A test is then performed during step 304 to deter- 
30 mine if there are additional PAGE keywords in the current 
specification parse tree to be processed. If it is deter- 
mined during step 304 that there are additional PAGE 
keywords to be processed, program control will return to 
step 302 and continue in the manner described above. 
35 If, however. It is determined during step 304 that 
there are no additional PAGE keywords to be processed, 
or if it was determined during step 302 that the command 
specification parse tree 22 does not include any PAGE 
keywords, then program control will proceed to step 305. 
40 A test is performed during step 305 to determine if 
the command specification parse tree 22 includes the 
COMMAND keyword, Indicating that a command Is be- 
ing specified. If it Is determined during step 305 that the 
command specification parse tree 22 does not contain 
45 the COMMAND keyword, program control will proceed 
to step 360 (FIG. 3d). 

If It is determined during step 305 that the command 
specification parse tree 22 does contain the COMMAND 
keyword, the documentation process 48 will enforce any 
50 command documentation rules, and then copy the com- 
mand syntax and parameter Information during step 310 
from the TEMPLATE segment of the command specifi- 
cation parse tree 22, such as would be associated with 
line 60 of FIG. 2a, into a header segment 410 of a com- 
55 mand documentation file 400, as discussed further be- 
low in conjunction with FIG. 4, that is created for stonng 
the documentation information associated with the com- 
mand. The command documentation file 400 being de- 
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veloped during execution of the documentation process 
48 may be stored in the memory unit 44. 

A test is performed during step 315 to determine if 
the command specification parse tree 22 includes a 
WARNING keyword, which would allow the programmer 
to provide a warning to a user regarding the Initiation of 
the command. If it is determined during step 31 5 that the 
command specification parse tree 22 does include a 
WARNING keyword, the documentation process 43 will 
enforce any warning documentation rules that have been 
defined and then copy the associated character string 
from the parse tree 22 during step 320 into a warning 
segment 415 of the command documentation file 400 as- 
sociated with the command, as discussed further below 
In conjunction with FIG, 4. 

If it is determined during step 31 5 that the command 
specification parse tree 22 does not include a WARNING 
keyword, an Indication that there are no warnings is pref- 
erably placed in the warning segment 415 of the com- 
mand documentation file 400 during step 322, as dis- 
cussed further below in conjunction with FIG. 4. In addi- 
tion, an error message could also be generated during 
step 322, as an indication to the person documenting the 
software that no warnings have been provided for the 
execution of this command. 

A test is performed during step 325 (FIG. 3b) to de- 
termine if the command specification parse tree 22 in- 
cludes a PURPOSE keyword. If it is determined during 
step 325 that the command specification parse tree 22 
does not include a PURPOSE keyword, a test is per- 
formed during step 328 to determine if the command 
specification for the current command should include a 
PURPOSE keyword and associated documentation in- 
formation. Under certain circumstances, the purpose 
documentation information for a given command may be 
obtained from another location or a default purpose mes- 
sage may be utilized. For example, as discussed above, 
the documentation for a number of related commands 
may be grouped on a single page. Accordingly, it may 
be desired to indicate a single purpose for the group of 
commands, without indicating the purpose of each indi- 
vidual command. 

If it is determined during step 328 that the PUR- 
POSE keyword and associated documentation Informa- 
tion is not necessary for this command, program control 
will proceed to step 340. If, however, it is determined dur- 
ing step 328 that the PURPOSE keyword is necessary 
for this command, an error or warning message should 
be generated during step 330, in order to ensure the 
completeness of the command documentation. Thereaf- 
ter, program control will proceed to step 340, described 
below. 

If, however, it is determined during step 325 that the 
command specification parse tree 22 does include a 
PURPOSE keyword, the documentation process 48 will 
enforce any purpose documentation rules and then copy 
the associated character string from the parse tree 22 
during step 335 into a purpose segment 420 of the com- 



mand documentation file 400 associated with the com- 
mand, as discussed further below in conjunction with 
FIG. 4. 

A test is performed during step 337 to determine if 
5 there are additional PURPOSE keywords to be proc- 
essed for this command. If it is determined during step 
337 that there are additional PURPOSE keywords to be 
processed, program control will return to step 325 and 
continue in the manner described above. 
10 if, however, it is determined during step 337 that 
there are no additional PURPOSE keywords to be proc- 
essed, a test Is performed during step 340 to determine 
if the command has associated parameters, as indicated 
in the TEMPLATE segment analyzed during step 310. If 
IS it is determined during step 340 that the command does 
not have associated parameters, program control will 
proceed to step 350 (FIG. 3c), described below. 

If, however, it is determined during step 340 that the 
command does have associated parameters, a test Is 
performed during step 342 to determine if the first de- 
fined parameter has a PARAMETER DESCRIPTION 
keyword. It is noted that If the command specification 1 0 
indicates that the parameter currently being analyzed is 
an enumerated list, the appropriate keyword identifying 
the description for each alternative character string will 
be DESC, such as in lines 750, 780, 810 and 840 of the 
command specification illustrated in FIG. 2a through 2d. 

If it is determined during step 342 that the command 
specification parse tree 22 does not include a PARAM- 
ETER DESCRIPTION keyword for the first defined pa- 
rameter, a test is performed during step 343 to determine 
if the command specification parse tree should include 
a PARAMETER DESCRIPTION keyword for the first de- 
fined parameter. Under certain circumstances, the doc- 
umentation information for a given parameter may be ob- 
tained from another location, such as the documentation 
library 75, or a default parameter description message 
may be utilized. 

If it is determined during step 343 that the PARAM- 
ETER DESCRIPTION keyword is not necessary for the 
first defined parameter, program control will proceed to 
step 350 (FIG. 3c), If, however, it is determined during 
step 343 that the PARAMETER DESCRIPTION keyword 
is necessary for the first defined parameter, an error or 
warning message should be generated during step 344, 
in order to ensure the completeness of the command 
documentation. Thereafter, program control will proceed 
to step 350 (FIG. 3c), as described below. 

If, however, it is determined during step 342 that the 
command specification parse tree 22 does include a PA- 
RAMETER DESCRIPTION keyword for the first defined 
parameter, the documentation process 48 will enforce 
any parameter documentation rules and copy the asso- 
ciated character string from the parse tree 22 during step 
346 into an explanation of parameter segment 425 of the 
command documentation file 400 associated with the 
command, as discussed further below in conjunction 
with FIG. 4. 
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A test is performed during step 348 to determine if 
there are additional parameters to be documented for 
this command. If it is determined during step 348 that 
there are additional parameters to be documented, pro- 
gram control will return to step 342 and continue in the 
manner described above. 

If, however, it is determined during step 348 that 
there are no additional parameters to be documented, a 
test is perfomned during step 350 (FIG. 3c) to determine 
if the command specification parse tree 22 includes a 
RESPONSES keyword. The RESPONSES keyword will 
preferably allow a programmer to document the expect- 
ed system response to the entry of the command, such 
as an acknowledgement. If it Is determined during step 
350 that the command specification parse tree 22 does 
not include a RESPONSES keyword, an indication that 
only standard system responses apply is preferably 
placed in a response segment 430 of the command doc- 
umentation file 400 during step 352, as discussed further 
below in conjunction with FIG. 4. 

If, however, it is determined during step 350 that the 
command specification parse tree 22 does include a RE- 
SPONSES keyword, the documentation process 48 will 
enforce any responses documentation rules and then 
copy the associated character string from the parse tree 
22 during step 354 into the responses segment 430 of 
the command documentation file 400 associated with the 
command, as discussed further below in conjunction 
with FIG. 4. 

A test is performed during step 355 to determine if 
there are additional COMMAND keywords in the current 
specification to be processed for this command. If it is 
determined during step 355 that there are additional 
COMMAND keywords to be processed, program control 
will return to step 305 (FIG. 3a) and continue In the man- 
ner described above. 

If, however, it is determined during step 355 that 
there are no additional COMMAND keywords to be proc- 
essed, program control will proceed to step 360 (FIG. 
3d). 

A test is performed during step 360 (FIG. 3d) to de- 
termine if the command specification parse tree 22 in- 
cludes a REPORT keyword, indicating that a report for- 
mat is being specified. It it is determined during step 360 
that the command specification parse tree 22 does not 
contain the REPORT keyword, program control will pro- 
ceed to step 385 (FIG. 3e), where the process will be 
exited. 

If it is determined during step 360 that the command 
specification parse tree 22 does contain the REPORT 
keyword, the documentation process 48 will enforce any 
reporf documentation rules and then copy the report 
heading and parameter information from the TEMPLATE 
segment of the specification parse tree 22, such as as- 
sociated with lines 240 through 270 of FIG. 2b. into a 
header segment 510 of a report documentation file 500 
that is created for storing the documentation information 
associated with the report during step 362. as discussed 



further below in conjunction with FIG. 5. The report doc- 
umentation file 500 being developed during execution of 
the documentation process 48 may be stored in the 
memory unit 44. 
s A test Is performed during step 364 to determine if 
the command specification parse tree 22 includes a 
PURPOSE keyword associated with the report specifi- 
cation. If it is determined during step 364 that the spec- 
ification parse tree 22 does not include a PURPOSE key- 
10 word for the report specification, a test is performed dur- 
ing step 365 to determine if the specification for the cur- 
rent report should include a PURPOSE keyword and as- 
sociated documentation information. Under certain cir- 
cumstances, the purpose documentation information for 
a given report may be obtained from another location or 
a default purpose message may be utilized. For exam- 
ple, as discussed above, the documentation for a 
number of related reports may be grouped on a single 
page. Accordingly, It may be desired to Indicate a single 
purpose for the group of reports, without Indicating the 
purpose of each individual report. 

If it is determined during step 365 that the PUR- 
POSE keyword is not necessary for this report, program 
control will proceed to step 370 (FIG. 3e). If, however, it 
is determined during step 365 that the PURPOSE key- 
word is necessary for this report, an error or warning 
message should be generated during step 366, in order 
to ensure the completeness of the command documen- 
tation. Thereafter, program control will proceed to step 
370 (FIG. 3e), as described below. 

If, however, it is determined during step 364 that the 
command specification parse tree 22 does include a 
PURPOSE keyword for the report specification, the doc- 
umentation process 48 will enforce any purpose docu- 
mentation rules and then copy the associated character 
string from the parse tree 22 during step 368 into a pur- 
pose segment 515 of the report documentation file 500 
associated with the report, as discussed further below in 
conjunction with FIG. 5. 

A test is performed during step 369 to determine if 
there are additional PURPOSE keywords to be proc- 
essed for this report. If it is determined during step 369 
that there are additional PURPOSE keywords to be proc- 
essed, program control will return to step 364 and con- 
tinue in the manner described above. 

If, however, it is determined during step 369 that 
there are no additional PURPOSE keywords to be proc- 
essed, program control will proceed to step 370 (FIG. 
3e). 

A test is performed during step 370 (FIG. 3e) to de- 
termine if the report has associated parameters, as indi- 
cated in the TEMPLATE segment analyzed during step 
362. If it is determined during step 370 that the report 
does not have associated parameters, program control 
will proceed to step 380, discussed below. 

If, however, it is determined during step 370 that the 
report does have associated parameters, a test is per- 
formed during step 372 to determine If the first defined 
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parameter for the report has a PARAMETER DESCRIP- 
TION keyword. It is noted that if the command specifica- 
tion 10 indicates that the parameter currently being an- 
alyzed is an enumerated list, the appropriate keyword 
identifying the description for each alternative character 
string will be DESC. such as in lines 750, 780, 810 and 
840 of the command specification illustrated in FIG. 2a 
through 2d. 

If it is determined during step 372 that the command 
specification parse tree 22 does not include a PARAM- 
ETER DESCRIPTION keyword for the first defined pa- 
rameter, a test is performed during step 373 to determine 
if the command specification parse tree should include 
a PARAMETER DESCRIPTION keyword for the first de- 
fined parameter for the report. Under certain circum- 
stances, the documentation information for a given pa- 
rameter for a report may be obtained from another loca- 
tion, such as the documentation library 75, or a default 
parameter description message may be utilized. 

If it is determined during step 373 that the PARAM- 
ETER DESCRIPTION keyword is not necessary for the 
first defined parameter for the report, program control will 
proceed to step 380. If. however, it is determined during 
step 373 that the PARAMETER DESCRIPTION keyword 
is necessary for the first defined parameter for the report, 
an error or warning message should be generated during 
step 374, in order to ensure the completeness of the 
command documentation. Thereafter, program control 
will proceed to step 380, as described below. 

If, however, it is determined during step 372 that the 
command specification parse tree 22 does include a PA- 
RAMETER DESCRIPTION keyword for the first defined 
parameter, the documentation process 48 will enforce 
any parameter documentation rules and then copy the 
associated character string from the parse tree 22 during 
step 376 into an explanation of parameter segment 520 
of the report documentation file 500 associated with the 
report, as discussed further below in conjunction with 
FIG. 5. 

A test is performed during step 378 to determine if 
there are additional parameters to be documented for 
this report. If it is determined during step 378 that there 
are additional parameters to be documented, program 
control will retum to step 372 and continue in the manner 
described above. 

If. however, It is determined during step 378 that 
there are no additional parameters to be documented, a 
test is performed during step 380 to determine if there 
are additional REPORT keywords in the current specifi- 
cation to be processed for this report. It it is determined 
during step 378 that there are additional REPORT key- 
words to be processed, program control will return to 
step 360 (FIG. 3d) and continue in the manner described 
above. 

If, however, it is determined during step 378 that 
there are no additional REPORT keywords to be proc- 
essed, program control will proceed to step 385, where 
the process will be exited. 



VSftien the documentation process 48 of FIGS. 3a 
through 3e has been performed on the command spec- 
ification for the op-ivspos command, shown in FIGS. 2a 
through 2d. a command documentation file, such as the 
s command documentation file 400 shown in FIG. 4, will 
result. As previously Indicated, the documentation proc- 
ess will analyze the command specification parse tree 
22 to identify certain documentation information that 
should be extracted from the parse tree 22 and placed 
in various segments of the command documentation file 
400. As shown in FIG. 4, the command documentation 
file 400 will preferably include a header segment 410, a 
warning segment 415, a purpose segment 420, an ex- 
planation of parameters segment 425 and a response 
segment 430. In addition, the command documentation 
file 400 may also include directions to the printer 65, such 
that when the command documentation file 400 is print- 
ed, it will contain certain features, such as a box around 
the header segment 410 and the warning segment 415. 

Similarly, following execution of the documentation 
process of FIGS 3a through 3e on the command spec- 
ification for the op'Wspos command, shown in FIGS. 2a 
through 2d, a report documentation file, such as the re- 
port documentation file 500 shown in FIG. 5, will result. 
As previously indicated, the documentation process will 
analyze the command specification parse tree 22 to 
identify certain documentation information that should be 
extracted from the parse tree 22 and placed in various 
segments of the report documentation file 500. As shown 
in FIG. 5, the report documentation file 500 will preferably 
include a header segment 510, a purpose segment 515 
and an explanation of parameters segment 520. In ad- 
dition, the report documentation file 500 may also include 
directions to the printer 65, such that when the report 
documentation file 500 is printed, it will contain certain 
features, such as a box around the header segment 51 0. 

As previously indicated, the documentatk5n files 
generated by the documentation file generator 40, such 
as the command documentation file 400 shown In FIG. 
4 or the report documentation file 500 shown in FIG. 5, 
may be formatted in a desired manner by the documen- 
tation processor 50. 

It is to be understood that the embodiments and var- 
iations shown and described herein are illustrative of the 
principles of this invention only and that various modifi- 
cations may be implemented by those skilled in the art 
without departing from the scope of the invention. 



Claims 

1. A method for generating user documentation for a 
software command to be executed by a computing 
system, said computing system interpreting said 
software command based on a high level language 
command specification that includes command 
specification information identified by one or more 
command keywords, said high level language com- 
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mand specrfication being translated into a form that 
may be executed by said computing system, said 
user documentation having a plurality of segments, 
said documentation method comprising the steps of: 

defining a plurality of documentation keywords 
for Identifying documentation Information state- 
ments in said command specification that describe 
the operation of said software command, each of 
said documentation keywords being associated with 
one of said segments of said user documentation; 

incorporating into said high level language 
command specification one or more of said docu- 
mentation information statements, wherein each of 
said documentation Information statements are 
identified In said command specification by one of 
said predefined documentation keywords; 

parsing said high level language command 
specification; 

extracting from said parsed command specifi- 
cation said documentation information statements 
identified by one of said predefined documentation 
keywords; and 

placing said extracted documentation informa- 
tion statements in said segment of said user docu- 
mentation corresponding to said associated docu* 
mentation keyword. 

2. The documentation method according to claim 1, 
wherein said execution of said software command 
by said computing system produces an output result 
and wherein said command specification includes 
specification information that defines said output 
result, and wherein said step of Incorporating docu- 
mentation information statements in said command 
specification further includes the step of incorporat- 
ing documentation information statements that 
describes said output result. 

3. The documentation method according to claim 2, 
wherein at least one of said segments In said user 
documentation is an output documentation seg- 
ment, and wherein said documentation Information 
statements describing said output result are placed 
in said output documentation segment. 

4. The documentation method according to claim 1, 
wherein at least one of said predefined documenta- 
tion keywords provides an Indication that said asso- 
ciated documentation information statement pro- 
vides a description of the purpose of said software 
command. 

5. The documentation method according to claim 1, 
wherein said command specrfication further 
includes specification information that defines one 
or more parameters associated with said software 
command and wherein at least one of said docu- 
mentation information statements Includes a 



description of said one or more parameters. 

6. The documentation method according to claim 5. 
wherein one or more of said parameter descriptions 

s are stored in a documentation library that may be 
accessed to generate said user documentation. 

7. The documentation method according to claim 1 , 
further including the step of processing said user 

10 documentation to generate one or more formatted 
pages for a user documentation manual. 

8. The documentation method according to claim 1 , 
further Including the step of ensuring that said com- 

is mand specification includes at least one of said doc- 
umentation information statements describing the 
operation of said software command. 

9. A method for generating user documentation for a 
20 software command to be executed by a computing 

system, said computing system interpreting said 
software command based on a high level language 
command specification that includes command 
specification information identified by one or more 

25 command keywords, said high level language com- 
mand specification being translated into a form that 
may be executed by said computing system, said 
documentation method comprising the steps of: 

defining a plurality of documentation keywords 

30 for identifying documentation information state- 
ments in said command specification that describe 
the operation of said software command, each of 
said documentation keywords having at least one 
associated rule to be performed upon recognition of 

35 said associated documentation keyword in said 
comnnand specification; 

incorporating into said high level language 
command specification one or more of said docu- 
mentation information statements, wherein each of 

40 said documentation information statements are 
identified in said command specification by one of 
said predefined documentation keywords; 

parsing said high level language command 
specification; 

45 extracting from said parsed command specifi- 

cation said documentation information statements 
Identified by one of said predefined documentation 
keywords; and 

processing said extracted documentation 

50 information statements based on said rule associ- 
ated with said documentation keyword identifying 
said documentation information statement. 

10. The documentation method according to claim 9, 
55 wherein one or more of said rules associated with 

said documentation keywords require said extracted 
documentation information statements to be con- 
sistent with standards established for said associ- 
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ated documentation keywords. 

11. The documentation method according to claim 9, 
wherein said rules associated with said documenta- 
tion keywords require documentation information s 
statements to be provided for less than all of said 
command specification statements. 

12. The documentation method according to claim 9. 
wherein said user documentation includes a plurality io 
of segments and wherein each of said predefined 
documentation keywords is associated with one of 
said segments of said user documentation. 

13. The documentation method according to claim 12, is 
wherein said processing step further includes the 
step of placing each of said extracted documenta- 
tion information statements in said segment of said 
user documentation corresponding to said associ- 
ated documentation keyword. 20 

14. The documentation method according to claim 12, 
wherein said rule associated with each predefined 
documentation keyword includes an indication of 
which of said segments of said user documentation 2S 
where said associated extracted documentation 
information statement should be placed. 
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SPECIFICATION { 

PAGE { 

part: 
sub j ect : 
features : 
commands : 
pathname : 

} 

PAGE { 

part: 
siibject : 
features : 
reports : 
pathname : 

} 

COMMAND { 



20; 
65; 

aOOOO; 
op-wspos ; 

cdoc/ 5cr /TMcmd/ op-wspos ; 

20; 
65; 

aOOOO; 
op_wspos ; 

cdoc / 5 c r / TMirp t / op_wspos ; 



} 



INITIATION MESSAGE 
MGWSPOS; 



} 



TEMPLATE { 
op-wspos: tp; 

PURPOSE { 



} 



"Prints the current defaults for 
the indicated trunk and line 
work station (TLWS) test 
position (TP) . " ; 



PARAMETER tp{ 

PARAMETER TYPE { 
domain: num; 
min : 1 ; 
max: 32; 
default: -1; 
) 

PARAMETER DESCRIPTION { 

"Trunk emd line workstation 

test position nmnber (1-32) ." 
) 



FIG. 2a 
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200 REPORT { 

210 INITIATION MESSAGE { 

220 MGWSPOS; 
) 

230 TEMPLATE { 

240 proto: "OP WSPOS" ; 

250 proto: "tP" 5 "ID" ! "TO" ! "FREQ" ! "LVL" 

! "T&M MODE" ! "OPD" ; 
260 proto : " — " !" — " »" " j" - i" •» 

I " n I ii_^.n . 

270 proto: tp lid ! to ! f req ! Ivl Imode 

!opd; 

} 

280 PURPOSE { 

290 "To list the cxirrent default of a 

TLWS (tr\ink and line workstation) 
TP (test position) . This report 
is generated as a result of an 
OP-WSPOS command- " 

} 

300 PARAMETER tp { 

310 PARAMETER TYPE { 

320 domain: nvim; 

330 mint 1; 

340 max: 32; 

350 default: -1; 

} 

360 PARAMETER DESCRIPTION { 

370 "TLWS TP n\imber (1-32)." 

} 

) 

380 PARAMETER id { 

390 PARAMETER TYPE { 

400 dom: n\am; 

410 min: 1; 

420 max: 32; 

430 default: 0; 

) 

440 PARAMETER DESCRIPTION { 

450 "TP identification number" 

} 

. ^ 

FIG. 2b 
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460 PARAMETER to { 

470 PARAMETER TYPE { 

480 domain: num; 

490 min: 1; 

500 max: 100; 

510 default: 1; 

) 

520 PARAMETER DESCRIPTION { 

530 "Time in hours before the TP 

will timeout. " 

} 

> 

540 PARAMETER freq { 

550 PARAMETER TYPE { 

560 domain : num ; 

570 min: 0; 

580 max: 4095; 

590 default: -1; 

} 

600 PARAMETER DESCRIPTION { 

610 "Frequency in hertz." 

} 

) 

620 PARAMETER Ivl { 

630 PARAMETER TYPE { 

640 domain: num; 

650 min: 0; 

660 max: 490; 

670 default: -1; 

} 

680 PARAMETER DESCRIPTION { 

690 "Level in decibels." 

} 

} 

. X 



FIG. 2c 
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700 PARAMETER mode { 

710 PARAMETER TYPE { 

720 domain: ENUMLIST 

730 ENUM TALK { 

740 text: "TALK"; 

750 desc: "User can talk and listen."; 

} 

760 ENUM MONITOR { 

770 text: "MNTR" ; 

780 desc: "user can only listen."; 

) 

790 ENUM TEST { 

800 text: "TEST"; 

810 desc: 'Phone on hold."; 

} 

820 ENUM NONE { 

830 text: "NONE"; 

840 desc: "No T&M phone in use."; 

} 

} 

} 

} 

850 PARAMETER opd { 

860 PARAMETER TYPE { 

870 domain: dn; 

} 

880 PARAMETER DESCRIPTION { 

890 "Outpulse digits." 

} 

) 



FIG. 2d 



BNSDOCID: <EP_0e94835A1_L> 



16 



EP 0694 835 A1 



300 




Identify list of commands or reports that should appear 
on same documentation page, and appropriate section 
or page where documentation should appear 



Yes 




From FIG. So® 
305 



To FIG. 3d 



Enforce command documentation rules, any, and copy command syntax 
and parameter information from TEMPLATE segment of command specification 
into a header segment of a documentation file associated with the command 



315 



322 




Yes 



Enforce waming documentation 
rules, if any, and copy associated 
character string into a waming 
segment of documentation file 



Place indication that there are 

no warnings in waming 
segment of documentation file 



320 
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© From FIG. 3a 



325 




Enforce purpose documentation 
rules, if any, and copy associated 
character string into a purpose 
segment of the documentation file 



337 



Yes 



Are 

there addltionaT 
PURPOSE keywords to b£ 
processed ? 



NoJ 



340 



Does 
the command have* 
associated parametei^ 



No 



FIG. 3b 



Yes 



343 



342 



PARAIS/IETER^ 
DESCRIPTION, 
^eyword^ 

Yes 



No 



Is 

PARAiy/IETEJ 
DESCRIPTION 

keyword 
jiecessaryj 



NYes 



Enforce parameter documentation mies, if 

any, and copy associated character 
string into an explanation of parameters 
segnrtent of the documentation file 



348 



Yes 



Are 

there additional^ 
parameters to be 
^cumentedl. 



No 



No 



© To FIG. 3c 
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From FIG. 3b 




352 



Place an Indication tiiat 
only standard responses 
apply In a response segment 
of documentation file 



Enforce responses documentation 
rules, if any, and copy associated cliaracter 
string into a response segment of 
tlie documentation file 



355 



Are 

there addltionar 
COMMAND Iceywords to. 
^ processed^ ^ 

No 

©To FIG. 3d 



Yes 



♦®ToFIG.3a 
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360 



B) From FIG. 3a, 3c or 3e 



E)ToFIG. 3e 



362 




Enforce report documentation rules, If any, and 

copy command name report heading and 
parameter Information from TEMPLATE segment 
of report specification into a header segment of 
a documentation file associated with the report 




Enforce purpose documentation rules, 
if any, and copy associated character 
string into a purpose segment 
of the report documentation file 



Are 

Yes ^^-'^here additionaT 
PURPOSE i<eywords to^ 
^e processed 



369 



©ToFIG.3e 



FIG. 3d 
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© From FIG. 3d 




Generate 

error 
message 



Enforce parameter documentation rules. If any, and 
copy associated character string into an explanation 
of parameters segment of the documentation file 



378 

Yeg^^J^^^""^ Are there 

additional parameters to be^ 
documented?. 



380 

Are there 
Additional REPORT keywords" 
^ tobe processed^ 



No 



Yes 



385 



© From FIG. 3d 
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430 
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OP-WSPOS COMMAND DOCUMENTATION FILE 



410 

^-OP-WSPOS: TPs a 
41 5-^^ Warning: none 



• PURPOSE 

Prints the current defaults for the indicated trunk and 
line workstation (TLWS) test position (TP). 



' EXPLANATION OF PARAIVIETERS 
a = Tmnk and line workstation test position number (1-32). 



•RESPONSES 
Only standard system responses apply. 



FIG. 4 
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500 



\ 



510 



515 



520 




EP 0 694 835 A1 



OP-WSPOS REPORT DOCUMENTATION FILE 

■OP WSPOS 

TP ID TO FREQ LVL T&M MODE OPD 
a b c d e f g 



• REPORT PURPOSE 
To list the current defaults of a TLWS (trunk and line work statton) 
TP (test position). This report is generated as a result of an 
OP-WSPOS command. 



► EXPLANATION OF PARAMETERS 
a = TLWS TP number (1-32). 
b s TP Identif toatlon number, 
c = Time In hours before the TP will timeout, 
d = Frequency in hertz, 
e = Level in decibels, 
f = T&M (talk and monitor) phone mode. 

MNTR - User can only listen. 

NONE - No T&M phone In use. 

TALK - User can talk and listen. 

TEST - Phone on hold, 
g = Outpulse digits. 



FIG. 5 
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# 



EP 0 694 835 A1 



European Patent 
Office 



EUROPEAN SEARCH REPORT 



ApplicmtioD Number 

EP 95 30 5028 



DOCUMENTS CONSIDERED TO BE RELEVANT 



Catetoiy 



8 
I 

a 

I 
s 

m 

I 



CkflCioD of do rnmm f whh indtcacioii. fvtere appropriate^ 
of rdevam passages 



MOTOROLA TECHNICAL DEVELOPMENTS, 
vol.17, December 1992, SCHAUMBURG, 
ILLINOIS US 
pages 87 - 89 

ROBERT TURNER 'A Program Documentation 
TooV 

* the whole document * 

PROCEEDINGS OF THE IEEE 1894 NATIONAL 
AEROSPACE AND ELECTRONICS CONFERENCE 
NAECON 1984, 

vol.2, May 21-25 1984, DAYTON, USA 
pages 687 - 694 

S. SENUPTA AND G. SNYDER: * Program 
Development with Byron' 

* page 687, right column, lines 2 - 18, 33 
- 38 * 

* page 690, left column, line 1 - page 
691, left column, line 45; figure 1 * 

* Examples 2 - 4 * 

* page 694, left column, line 38 - line 46 



EP-A-0 261 845 (IBM) 30 March 1988 

* abstract * 

* column 1, line 46 - column 2, line 29; 
figure 1 * 

* column 3, line 20 - column 4. line 7 * 



Tbe present scardi report has been 4nm up for alt daims 



THE HAGUE 



1-14 



1,4,7-9, 
12-14 



1.9 



17 November 1995 



CLASSinCATlON OF THE 
APPUtATION anLCI.6) 



G06F9/44 



TECHNICAL FIELDS 
SEARCHED aikt.CL6) 



G06F 



Fonderson, A 



CATEGORY OF CTTEO DOCUMENTS 

X : partiaitmrly relevant if fcUcca alone 

Y : paniailarly relevant if comMaed with aaolhcr 

docniBcnt of the suae category 
A : techmlogical backgroimd 
O : aoB*iiritlai disdosnre 
P : iBtefBcdbte docoBMat 



T : theory or priadple uadcflyiag the 
E : earlier patent dooiiacnt, I ' 

after the filias date 
D : documat dted ia the applicatioa 
L : docnmcat dted for other rcasoas 



A : member nf t 



t pateat family, eaeres^diag 



BNSDCX:iD: <EP 0694835A1_L> 
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BNSDOCiD: <EP 069483SA1TL> 



12 



EP 0 694 635 A1 



02 
D4 
06 
08 
10 
12 
14 

16 
13 
20 
22 
24 
26 

30 
35 
40 

50 
60 

70 
60 



90 

100 

110 

120 

130 

140 

150 
160 



SPECIFICATION 

PAGE < 

part J 
sui> j ect : 
features : 
commands : 
patbnaiDe: 

> 

FAGS { 

part : 
subject : 
features ; 
reports : 
pathxiaine : 

} 

COMMAND C 



20; 
65; 

aOOOO; 
op-wspos; 

cdoc/Scr/lMcmd/op'Wspoa ; 



20j 
65; 

aOCOOr 
op_wspos r 

cdoc/Ser/macpt/op^wspos; 



INITIATION HESSAOE 
MGWSPOSr 



> 



TEMFXATE { 
Op-wspos ! tPi 

PURPOSE { 



'Prints the current defaults for 
the indicated trunk arid line 
work station (TLWS) teat 
position (TP} . 

PAFAMETER tp{ 

PARAMETER. TYPE ( 
djcutiain; n^um? 
man; 1 ; 
max: 12; 
defaults -1; 
} 

PAJiAMETER DESCRIPTION ( 

"Trunk and line -workstaticn 

test poslticn. number (1-32) .* 
} 



RG. 2a 
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200 REPORT { 

310 INITIATIOH MESSAGE { 

220 MGWfiPOS; 
) 

23 Q TEMPLATE { 

240 proto; "OPWSPOS"? 

250 protoj ii^pii iniijii I "TQii M'PKEQ- i "lvL" 

! "TtM MODE" J "OPD" ; 
260 pro to 3 in«_(i Ml ____ ■ J 11 II 

270 proto: tp lia ! to Ifreg iXvl J mode 

!opd; 

) 

260 PURPOSE C 

290 -To list th© current default of a 

TLWS (trtmJc and line worXetationJ 
TP (test position) . This report 
is generated &si a. result of an 
OP-WSFOS coinniBnd, " 

) 

300 PARAMBTBK tp { 

310 PARAttETER TYPE { 

320 domain! num; 

330 mini 1? 

340 maxt 32; 

350 default; -1; 

} 

360 PARSJIETER DESCatPTION { 

370 'TLWS TP number (1-32K" 

} 

} 

380 PARAMETER id { 

390 FARAMBTER TYPE { 

400 dom: num; 

410 min: 1; 

420 max: 32; 

430 default: 0; 

} 

440 PARAMETER DESCRIPTION { 

450 -TP identification niuabar" 

) 

FIG. 2b 
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460 PARAMETER to ( 

^■^O PARAMETER TYPE { 

*S0 domain: mjun? 

490 iftin: 1; 

500 max: lOQ; 

510 default: 1; 

} 

520 PARAMETER DESCRIPTION { 

530 -Time in hours before tli« TP 

will timeout.* 

) 

} 

54 Q PARAMETER freq { 

550 PARAMETER TYPE ( 

560 domain: nun; 

570 min: 0; 

530 max: 4095; 

590 default: -Ij 

> 

600 PARAMETER DESCRIPTION { 

510 •Frequency in hertz." 

> 

} 

620 PARAMETER Ivl ( 

630 PARAMETER TiPE ( 

6^0 domain: nurti? 

650 min: 0; 

660 max: 490; 

€70 default: -1; 

} 

6 BO PARAMETER DESCRIPTION { 

690 "Laval in decibel©. " 

) 

) 



FIG. 2c 
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PARAMETER node { 
710 PARAMETER TYPE { 

720 domain I ENUftlLrST 

730 BWUM TAIiK < 

740 text: -TALK"; 

750 desc: 'User can talk and Listen."; 

} 

760 ENUW MONITOR { 

770 text: "MHTR*; 

780 de$c; "user can only llflten."; 

} 

790 ENDM TEST { 

300 text: "TRST»; 

810 de^c: "Phone on hpld,"; 

J 

820 ECraH N017E { 

8^0 text : "NONE' ; 

640 desc: "Nc T6M phone in -use."/ 

} 

} 

} 

> 

350 PARAHOTER opd { 

060 PARAMETER TYPE { 

870 domain I dn? 

> 

980 PARAMETER DESCRIPTION ( 

890 "Outpulse digits." 

} 

> 



FIG. 2d 
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Identify list of oommands or reports that should appear 
on same documentation pa^e, and appropriate section 
or papa where documentaaon ahould appear 




From HQ. 3c® 
305 



K§) lb FIG. 3d 



Enfonca oommand documentation miss, \i any, and copy command syntax 
and parameter infoimatbn from TEMPLATE seoment o1 command epeciflcation 
into a header segmem et a dgcumenlatlon file aseooiatgd wrih the command 




Enforce warning documentation 
ruiea, If any, and copy associated 
character atring Into a wanning 
segment of documantatlon file 



Place Indication that there are 
^ no warnings In warning 
segment ot documentation file 



1 



To FIG. 3b 



320 



-J FIG. 3a 
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© From FIG. 3a 




To FIG, 3c 



IS 
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From FIG, 3b 



350 



354 




3S2 



PlacQ an indicatioh that 
only standard responses 
apply in a response segment 
of documentation file 



Enforce responses documentation 
rules, If any, and copy associated character 
atring Into a response segment of 
the documentation file 



355 



Are 

there additicnt 
COMMAND keywords iq, 
processed^ ^ 

No 

S) To FIG. 3d 



Yes 



*<S)ToFIG.3a 



FIG. 3c 
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360 



1) From FIG. 3a, 3c or 3e 



^iMDTbFIQ,3e 



362 




Enforce report documentation rules, if any, anci 

copy command nam» report heading and 
parameter informatton from TEMPUVTE segnwnt 
of report specification into a header segment of 
a documentation file associated with the report 



364 



368 




366 



Generate 
error meseaQe 



Enforce purpose documentation rules, 
If any, and copy associated character 
string Into a purpose cegment 
of the report documentation flie 



Are 

Yes ^^-"^here additional 
PURPOSE keywordd to 
wpraceesed^ 



369 



No] 



To FIG, 3e 



FIG. 3d 
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From FIG. 3d 




Generate 

error 
meaeege 



Enforce parameter docvngnlatlon lutaB, if any, and 
oopy associated character siring into an axplarkaiion 
of perametere segment of tlie documentation file 



378 

Yes_,.->'^'^ Are there 

additional parameters to be^ 
^ dcKjmented?^ 



380 

Are there^ 
;^i1ional REPORT iceywords; 
be processed 



No 



Yea 



It FIQ. 3d 



36£ 



Ndl 
EXIT 



From FIG, 3d 



FIG. 3e 
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400 

\ 



420 



425 



430 
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OP^WSPOS COMMAND DOCUMENTATION FfLE 



410 

^^OP-WSPOS; TP = a 
41 5^^^ Warning: none 



PURPOSE 

Prints the current d^ults for the indicated trunk and 
line vrarkstatlon (TLWS) test position (TP) 



' EXPLANAirON OF PARAMETERS 

a = Trunk and line workstation taat position number (1-32). 



RESPONSES 

Only standard system responses apply. 



FIG. 4 
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500 



\ 



510 



515 



OP-WSPOS REPORT DOCUMENTATION RLE 

-OP 

TP ID TO PRBO LVIj T&M MODE OPD 

a b c d e £ a 



• REPOFTT PURPOSE 

To list the current defaults oi a TLWS (trunk and line work station} 
TP (test po&ltlon). This report Is generated 86 a result of an 
OP-WSPOS command. 

* EXPLANATION OF PARAMETERS 
a = TLWS TP number (t-32), 

b = TP identification number. 

0 = Time in hours before the TP will timeout. 

d = Frequency In hertz. 

e = Level in deolbets. 

f = T&M (talk and monitor) phone mode. 

MNTR - User can only listen. 

NONE - No T&M phone In use. 

TALK - User can talk and listen. 

TEST - Phone on hold, 
g = Outpulse digits. 



FIG, 5 
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